images in 3D frame: Images in 3-D plots.

Description

image3D adds an image in a 3-D plot.

Usage

image3D (x = NULL, y = NULL, z = NULL, ..., colvar = NULL, 
      phi = 40, theta = 40, col = jet.col(100), 
      NAcol = "white", border = NA, facets = TRUE,
      colkey = NULL, resfac = 1,
      panel.first = NULL,
      clim = NULL, clab = NULL, bty = "b",
      inttype = 1, add = FALSE, plot = TRUE)

Arguments

x, y, z

Matrix (2-D), vector, or one value containing the values where the image is to be plotted. At least one of them should be one number, as this will determine where the image is plotted, parallel to the (y-z) plane (x one number), to

colvar

The variable used for coloring.

col

Color palette to be used for the colvar variable.

NAcol

Color to be used for NA values of colvar; default is ``white''.

colkey

A logical, NULL (default), or a list with parameters for the color key (legend). List parameters should be one of

side, plot, length, width, dist, shift, addlines, col.clab, cex.clab,
      side.clab, line.clab

clab

Only if colkey = TRUE, the label to be written on top of the color key. The label will be written at the same level as the main title. to lower it, clab can be made a vector, with the first values empty strings.

clim

Only if colvar is specified, the range of the color variable, used for the color key. Values of colvar that extend the range will be put to NA.

resfac

Resolution factor, one value or a vector of two numbers, for the x and y- values respectively. A value > 1 will increase the resolution. For instance, if resfac equals 3 then for each adjacent pair of x- and y-v

theta, phi

The angles defining the viewing direction. theta gives the azimuthal direction and phi the colatitude. see persp.

border

The color of the lines drawn around the surface facets. The default, NA, will disable the drawing of borders.

facets

If TRUE, then col denotes the color of the surface facets. If FALSE, then the surface facets are colored ``white'' and the border (if NA) will be colored as specified by co

panel.first

A function to be evaluated after the plot axes are set up (and if applicable, images or contours drawn) but before any plotting takes place. This can be useful for drawing background grids or scatterplot smooths. The functio

bty

The type of the box, the default only drawing background panels. Only effective if the persp argument (box) equals TRUE (this is the default). See pers

inttype

The interpolation type to create the polygons, either taking the mean of the colvar variable (inttype = 1, 3 or extending the x, y, z values (inttype = 2). Values 1, 3 diff

add

Logical. If TRUE, then the image will be added to the current plot. If FALSE a new plot is started.

plot

Logical. If TRUE (default), a plot is created, otherwise the viewing transformation matrix is returned (as invisible).

...

additional arguments passed to the plotting methods. The following persp arguments can be specified:

xlim, ylim, zlim, xlab, ylab, zlab, main, sub, r, d, 
    scale, expand, box, axes, nticks, ticktyp

Value

Returns the viewing transformation matrix. See trans3D.

Details

image3D calls the surf3D function. The x, y, and z values are expanded as a matrix.

Examples

Run this code

# save plotting parameters
 pm <- par("mfrow")

## =======================================================================
## images in x, y, z plane
## =======================================================================

 par(mfrow = c(2, 2))

# images in x, y, z plane
# We use colkey = list(plot = FALSE) to create room for a color key
 image3D(y = seq(0, 1, 0.1), z = seq(0, 1, 0.1), x = 0.5, 
   col = "blue", xlim = c(0,1), colkey = list(plot = FALSE))
 image3D(x = seq(0, 1, 0.1), z = seq(0, 1, 0.1), y = 0.5, 
   add = TRUE, col = "red", alpha = 0.2)   # alpha makes it transparent
 image3D(x = seq(0, 1, 0.1), y = seq(0, 1, 0.1), z = 0.5, 
   add = TRUE, col = "green")
 colkey(col = c("green", "red", "blue"), clim = c(0.5, 3.5), 
   at = 1:3, labels = c("z", "y", "x"), add = TRUE)
#
 image3D(z = 100, colvar = volcano, zlim = c(0, 150),
   clab = c("height", "m"))
  
#
 image3D( x = 0.5, colvar = volcano, xlim = c(0, 1), 
   ylim = c(0, 1), zlim = c(0, 1))

 image3D( y = 0.5, colvar = volcano, add = TRUE)

#
 image3D( z = 1, colvar = volcano, 
   x = seq(0, 1, length.out = nrow(volcano)),
   y = seq(0, 1, length.out = ncol(volcano)), 
   xlim = c(0, 2), ylim = c(0, 2), zlim = c(0, 2))
 image3D(y = 2, colvar = volcano, add = TRUE, 
    shade = 0.2,
    x = seq(0, 1, length.out = nrow(volcano)),
    z = seq(1, 2, length.out = ncol(volcano)))
 image3D(x = 2, colvar = NULL, col = "orange", add = TRUE, 
    y = seq(0, 1, length.out = nrow(volcano)),
    z = seq(1, 2, length.out = ncol(volcano)))

# reset plotting parameters
 par(mfrow = pm)